Prizm Services will expect a source document to be provided for each new viewing session using one of three available methods. The specific method of transfer used for a particular document is specified during the creation of the viewing session, so it is possible to use multiple transfer methods in your application. You can transfer your document to Prizm Services by sending it explicitly with a HTTP PUT request or by specifying a file location, such as an HTTP URL or a local filename, so that Prizm Services can retrieve it.

The best transfer method for your application will likely depend on the original location of your documents. For example, if your source documents are stored in a database, the HTTP PUT request is likely the most efficient method as you’ll be able to read the data out of the database and copy it directly to the request body, eliminating the need to write the document to a file. If your source documents are already hosted and accessible from an HTTP URL, Prizm Services can download the file directly thus eliminating any intermediate transfers. Finally, if your source documents already exist on the server that is hosting Prizm Services then providing the local path to each file is a good option.

The following sections provide some specific information about each transfer method. Additional information can also be found in the Viewing Sessions topic.

HTTP PUT Request

The PUT request is considered the default method of transferring source documents to Prizm Services. It provides the most independent method of transferring documents because the data is sent directly to Prizm Services, largely reducing the chances of a failure as compared to the other methods.

The request has the following format:

PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={ext}

The document data should be included directly in the request body. This request should be made after the HTTP POST request to create a viewing session and before the HTTP POST to start a viewing session.

HTTP URL

Prizm Services supports downloading a document from an HTTP or HTTPS URL. The URL must either be publicly accessible, or at least accessible over the internal network to which Prizm Services is connected.

The HTTP PUT request is not required if this transfer method. Instead, some JSON properties in the body of the HTTP POST request to create a new viewing session must be set appropriately. These specific properties are described below. See the Prizm Services API topic for more details about other JSON properties set in this request.

To enable the HTTP URL transfer method, set the documentSource JSON property to http. This will inform Prizm Services to expect a valid URL to be specified by the externalId JSON property. Set the externalId JSON property to the HTTP URL of your document. Prizm Services will require a valid extension be provided as well. You can set the extension explicitly with the documentExtension JSON property. If documentExtension is not set, Prizm Services will attempt to extract an extension from the end of the URL resource name. For example:

POST /ViewingSession
{
    "documentSource": "http",
    "externalId": "http://localhost/osha.pdf",
    "documentExtension": "pdf"
}

When Prizm Services receives the POST request to create the viewing session, it will begin downloading the document asynchronously in a background thread while the request returns with a status of 200 OK. Because the document download occurs asynchronously within Prizm Services, it is possible that the retrieval process will fail without any immediate feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of Document download failed.

There is a user-configurable timeout value that Prizm Services will use when it sends the GET HTTP request to download the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the Prizm Services Configuration topic for details about other user-configurable properties.

For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the externalId JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the Prizm Services Configuration topic for details about this and other configuration properties.

Local File

The third option to transfer documents makes use of the local file system to make your documents available to Prizm Services. This option is enabled by setting the documentSource JSON property to file. This will inform Prizm Services to expect a valid local file name to be specified by the externalId JSON property. Set the externalId JSON property to the filename of your document. Prizm Services will require a valid extension be provided as well. You can set the extension explicitly with the documentExtension JSON property. If documentExtension is not set, Prizm Services will attempt to extract an extension from the end of the filename given.

POST /ViewingSession
{
    "documentSource": "file",
    "externalId": "myDocumentStore\\osha.pdf",
    "documentExtension": "pdf"
}

For security purposes, only partial/relative paths and filenames are supported in externalId. Rooted paths are not supported. Instead, the root directory where your documents will exist should be specified in pcc.config using the UserDocumentFolder property. Prizm Services will combine the root directory in this property with the value it receives in externalId. If, when combined, a relative path in externalId takes the current directory outside of the directory specified in UserDocumentFolder, or any other invalid path is used, the transfer will fail.

The following are examples of valid values for externalId:

• "sample.doc"

• "docFolder\\sample.doc" (Windows)

• "docFolder/sample.doc" (Linux)

When Prizm Services receives the POST request to create the viewing session, it will copy the document asynchronously in a background thread while the request returns with a status of OK. Because the document is copied asynchronously within Prizm Services, it is possible that the retrieval process will fail without any immediate feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of Document download failed.

There is a user-configurable timeout value that Prizm Services will use when it copies the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the Prizm Services Configuration topic for details about other user-configurable properties.

For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the externalId JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the the Prizm Services Configuration topic for details about this and other configuration properties.

©2014. Accusoft Corporation. All Rights Reserved.